
\chapter{Architecture Explorer}
\label{chap:architecture-explorer}

%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
\section{Features}

\paragraph*{Further meta-information}
\subparagraph*{Relationships.}
Architecture Explorer does not only display relations that are part of some pattern 
implementation, but it also displays standard relations from 
object oriented design. These are inheritance, association, aggregation, composition and 
uses. Architecture Explorer reverse engineer these relations using source 
code analysis, but difference between some of them might be just semantic. 
For the purpose of the differentiation of these relationships Patterns4Net 
provides, besides attributes for patterns participants annotation, also 
attributes for annotating relations. Rules for reverse engineering of 
relations are summarized in the following listing.

\begin{itemize}
	\item When a class A has a field of type B without any annotation, then the association 
		from A to B is constructed. (The construction of cardinality of associations and 
		other relationships is described below.) 
	\item When a class A has a field of type B annotated with attribute 
		\inlinecode{Composition}, \inlinecode{Aggregation} or \inlinecode{Uses}, 
		then the relationship of composition, aggregation or uses from A to B is constructed.
	\item  When at least one of class's A methods invokes the constructor of 
		class B, has a parameter of type B or invokes a static method or 
		property from B, then uses relation from A to B is constructed.
\end{itemize}

\subparagraph*{}
Uses relation from A to B is not added when the composition or 
aggregation relation from A to B was discovered. 
Default cardinality is one-to-one. If the field of a class A 
is of a type which is assignable to \inlinecode{IEnumerable<B>} then 
the type \inlinecode{B} will be used in relation, and the cardinality of 
the relation will be set according to the rules below. 

\begin{itemize}
	\item  If the field is annotated with \inlinecode{ManyToMany} attribute 
		then the relation's cardinality will be many-to-many.
	\item  If the field is not annotated with \inlinecode{ManyToMany} attribute, 
		but there is also field of type \inlinecode{IEnumerable<A>} in B, 
		then the relation's cardinality will be many-to-many.
	\item  Otherwise the cardinality will be one-to-many.
\end{itemize}

\subparagraph*{}
\emph{
Architecture Explorer is not capable of discovering the uses relation 
if the constructor or static member invocation is hidden in reflection 
API calls. 
Uses relation is constructed even if the constructor or static 
member invocation is in the dead branch of code, 
which means that the constructor or static member will actually never be invoked. 
Architecture Explorer also does not check whether method's parameters 
are actually used inside the method's body.
}

\subparagraph*{Layers and packages.}
Architecture Explorer does not support hierarchical packages like UML does, 
but instead provides a concept of \emph{Layer} which is a container for 
packages. Normally \emph{Layers} correspond to each .NET assembly, but 
users can define \emph{Layers} on their own using assembly attribute as 
in the figure \ref{fig:layerattr}. First level namespaces in 
a layer are reverse engineered as packages. 

	\begin{figure}[h]				
		\begin{minted}[bgcolor=codebg]{csharp}
using Patterns4Net.Attributes;
[assembly:Layer("Layer Name", "Namespace")]
// safer definition using reflection, 
// a namespace of MyType will be used.
[assembly:Layer("Layer Name", typeof(MyType))]
		\end{minted}		
		\caption{Definition of \emph{Layer} using assembly attributes.}
		\label{fig:layerattr}
	\end{figure}
	
\paragraph*{Inputs}	
\subparagraph*{}
Basic input for Architecture Explorer is an assembly or set of assemblies to 
analyze. Instead of a assembly file, users can also choose Visual Studio C\# 
project files or Visual Studio solutions, in this case the tool will extract 
information about assemblies location from these files. 

\paragraph*{Outputs}
\subparagraph*{}
Architecture Explorer has interactive graphical user interface (GUI). 
It displays class diagrams on the four levels of abstraction allowing user to 
view the architecture from higher level overview (\emph{Layers level}) to 
detailed diagram of specific class and all it's collaborators (\emph{Class level}). 
Relationships and classes that play a role in some pattern implementation 
are graphically remarked. In the following paragraph we describe how the 
Architecture Explorer chooses which classes will be displayed at which level. 
Before that we introduce a related terminology.

\subparagraph*{}
Classes that implement patterns \pattern{Entity}, \pattern{AggregateRoot} or 
\pattern{ValueObject} known from Domain-Driven-Design approach are level 0 
classes. Classes that implement some infrastructural pattern like 
\pattern{Null Object} or \pattern{Helper Class} are level 2 classes. 
Other classes belong to level 1. Users can define their own patterns and 
assign them into any level. Levels of build in patterns are defined in xml 
configuration file and can be changed by users as well. Term element 
denotes a class, a class member, a package or a layer.

\subparagraph*{}
Now we can define all four levels of abstraction that Architecture Explorer 
provides.

\begin{itemize}
	\item Layers level -- layers are displayed as rectangles. Each one 
		contains it's packages, which are displayed as well as rectangles. 
		All elements have labels. If there is a class in a layer A which 
		is in relation with a class in a layer B, then the relation 
		is displayed between the layers A and B. If there are more relations 
		of the same type between A and B, only one is displayed.
	
	\item Layer level -- if the layer contains at least one class of level zero, 
	then these classes are displayed. Otherwise first level classes from the 
	layer are displayed. Classes have labels with their names, but members are 
	not displayed. Packages are displayed as rectangles and contain 
	corresponding classes. 
	
	\item Package level -- classes from the package are displayed. 
		\begin{itemize}
			\item If the package contains at least on class of level zero, then 
			classes of level zero and one are displayed.
			\item If the package does not contain any class of level zero, 
			then classes of level one and two are displayed.
		\end{itemize}
	
	\item Class level -- selected class is displayed with all it's methods 
	and properties. All classes from any package or any layer that are in 
	any relationship with this class are displayed. Classes are gathered 
	in rectangles that represent packages.
	
\end{itemize}


%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
\section{User Interface}
\paragraph{}
\subparagraph*{}
User interface of Architecture explorer consists of the content area in 
the center of the window, where the diagram is displayed, a toolbox on 
the top and various dockable panels. The toolbox contains buttons that 
serves to control the the program and the panels display additional 
information about the diagram. %maybe a figure...

\subparagraph*{}
Architecture Explorer displays only one diagram at once. If an 
assembly is loaded, it's content is added into the current diagram. 
Therefore, if two assemblies are consequently loaded, the diagram 
will contain all elements from both of them. If there are some already 
loaded elements in the diagram and a user wants Architecture Explorer 
to display only elements from another assembly, he must use a button that 
clears the diagram before loading the new assembly.

\subparagraph*{}
A user can browse through the diagram using either buttons in the toolbar, 
or by clicking on elements displayed in the diagram. A click on a diagram 
element causes that approriate level is displayed -- if the click was on 
a class, a class level is displayed, and likewise for other element types. 
A button intended to go up to next higher level is available in the toolbar 
as well as the buttons intended to go back and foward during the navigation 
through the diagram.

\subparagraph*{}
Dockable side panels display additional information. There are five of them 
\begin{itemize}
	\item{Diagram Browser displays all diagram elements in the treeview.}
	\item{Pattern Documentation displays descriptions of all patterns where 
	the currently selected class plays the main role.}
	\item{Properties panel displays information about current element. 
	These information may also contain an API documentation if available.}
	\item{Output window displays warning and informal messages for user. 
	These messages are generated during loading of an assembly or when 
	Pattern Enforcer is runnig.}
	\item{Errors window contains a gird that displays errors 
	from Pattern Enforcer.}
\end{itemize}

\subparagraph*{}
Architecture Explorer can display API documentation generated from source code. 
Source of this documentation is a xml file produced by C\# compiler. 
In Visual Studio to set up the compiler to produce this file, 
a user has to open the project properties panel, switch to the build tab 
and check the option "XML documentation file". Architecture Explorer expects 
the documentation file to have a default name and to be located in the same 
folder as the assembly.

\subparagraph*{}
Patterns documentation is loaded from the \inlinecode{patterns.xml} file, whose 
format is described in the \inlinecode{patterns.xsd} file. Patterns 
in the \inlinecode{patterns.xml} file are identified by the full name of the 
class that represents the pattern. For pattern documentation an xml dialect 
based on standard .NET API documentation format is used. 
To add a documentation for a custom pattern, a user should edit this xml file.  

\subparagraph*{}
When Pattern Enforcer is invoked from the Architecture Explorer, errors are 
displayed in special side panel and when a user clicks on the error, the 
diagram will zoom to class, where the error occured.

\paragraph{Definition of custom pattern.}
\subparagraph*{}
The definition of a custom pattern is described in section \ref{sec:patternenforcerusage}. 
The \inlinecode{IPattern} interface, which is required to be implemented 
by a class that represents a pattern, has the readonly \inlinecode{AbstractionLevel} 
property. Value of this property is used by Arcitecture Explorer to 
decide at which abstraction level it will display classes that play the 
main role in this pattern. 

\subparagraph*{}
The class that represents a pattern might have properties that 
represent the pattern roles. To direct Architecture Explorer to emphasize 
relationships between the main role of the pattern and the other roles, 
the properties representing the roles might be annotated with the 
\inlinecode{PatternRoleAttribute} attribute. This attribute allows to 
define the type of the relation (composition, aggregation, ...), 
the abstraction level of the relation, a cardinality, and a name. If 
a default value is provided for any of these properties, 
Architecture Explorer tries to infer the value from the source code.

\subparagraph*{}
To inform Architecture Explorer about assemblies that contain custom patterns 
a xml configuration file can be used. This xml file is an extension of the 
format used for Pattern Enforcer only and thus can be used for both tools. 
All configuration files and their schema definitions are located in the 
\emph{Config} folder.


%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
\section{Architecture}

\paragraph*{}
\subparagraph*{}
Architecture Explorer is developed in Windows Presentation Foundation (WPF). 
There are two reasons for choice of WPF. We wanted to use so called 
\pattern{Model-View-ViewModel} (\cite{mvvm:Online}) pattern and implementation of 
this pattern is easier in WPF than in Windows Forms. The second 
reason involves possible future work on Architecture Explorer. 
WPF applications can be, with some effort, ported to Silverlight, which 
can run in a Web browser and is supported also on other platforms than 
Windows.

\subparagraph*{}
A large portion of Architecture Explorer functionality is generation 
of "nice looking" graphs. For this purpose the \emph{Graphviz} 
(\cite{graphviz:Online}) tool is used, but it's adoption to WPF is not 
as easy as it might seem at first look, so it resulted in an introduction 
of separate project called Graphviz4Net, which is discussed in the 
following chapter.

\subsection{Model-View-ViewModel}
\paragraph*{}
\subparagraph*{}
The \pattern{Model-View-ViewModel} pattern is a variation of well known 
\pattern{Model-View-Controller} pattern. It's detailed description 
could be found in the article \cite{mvvm:Online}. The \pattern{ViewModel} 
is an object that supplies data to be displayed in the \pattern{View} as values 
of regular properties and it provides actions that could be invoked from 
the \pattern{View} (e.g., by clicking on a button) as regular methods. 
The \pattern{ViewModel} encapsulates all the user interface logic, 
but it does not handle displaying the data and therefore it could be an 
instance of a plain C\# class. The connection between the \pattern{ViewModel} 
and the \pattern{View}, which is WPF specific user control, is not handled 
by the objects themselfs but is driven by powerful data-binding features of WPF.

\subparagraph*{}
To ease the implementation of the \pattern{Model-View-ViewModel} pattern even 
more, Caliburn.Micro framework (\cite{caliburn:Online}) is used. It is 
capable of applying the \pattern{ViewModel} to \pattern{View} binding, 
\pattern{ViewModel} data to \pattern{View} visual elements binding and 
actions binding only according to naming conventions. For example, for the 
\inlinecode{ShellViewModel} class there is the \inlinecode{ShellView} WPF 
control and their binding is handled by Caliburn.Micro. 

\subparagraph*{}
The figure \ref{fig:viewmodels} shows the layout of the graphical user interface of 
Architecture Explorer. The \pattern{ViewModel} classes are located 
approximately in the same place, where they will be displayed by their 
corresponding \pattern{View} WPF controls. The whole window is represented 
by the \inlinecode{ShellViewModel} class, which aggregates all the other 
\pattern{ViewModel} objects.

	\begin{figure}[h]
	  \mbox{\includegraphics[width=\textwidth]{images/viewmodels.eps}}
	  \caption{Decomposition of the user interface into several ViewModel classes.}
	  \label{fig:viewmodels}
	\end{figure}

\subparagraph*{}
The \pattern{ViewModel} objects communicate either directly, or through events. 
Events are represented by C\# classes. When an object wants to publish an 
event it invokes the \inlinecode{Publish} method on the \inlinecode{EventAggreator} 
object, which is a singleton. This method has one argument, which is an 
object that represents the event and it's arguments. If an object wants to 
be notified when an event of certain type \inlinecode{T} is published, 
it has to implement the \inlinecode{IHandle<T>} interface and register itself 
to the \inlinecode{EventAggreator} object. 
Events mechanizm is used for handling selection of current element and 
navigation in diagram, because these actions might be invoked from several 
panels and might cause an update of several GUI elements.

\subsection{Diagram Classes Design}
\paragraph*{}
\subparagraph*{}
A diagram is represented by hierarchy of classes that are 
depicted in the figure \ref{fig:diagramclasses}. Each of these classes 
inherits from the base class \inlinecode{DiagramElement}, which means that 
each instance of these classes have a reference to it's parent object. 
The top level \inlinecode{Diagram} object returns a reference to itself 
as the value of this property.

	\begin{figure}[h]
	  \mbox{\includegraphics[width=\textwidth]{images/diagramclasses.eps}}
	  \caption{Hierarchy of classes that represent a diagram.}
	  \label{fig:diagramclasses}
	\end{figure}

\subparagraph*{}
Each type of relationship is represented as a separate class, because 
graphical templates for 

\subparagraph*{}
Becuase the diagram class structure is not likely to change often, the 
\pattern{Visitor} pattern is used to add new operations of the diagram 
elements. The base class for all \pattern{Visitors} is the 
\inlinecode{DiagramVisitor} class. The \pattern{Visitor}'s traversing 
algorithm is implemented in the diagram elements \inlinecode{Visit} method.

\subparagraph*{}
When an assembly should be loaded into the diagram, 
the \inlinecode{CecilDiagramLoader} loads all the layers, packages, types, 
methods and properties, but it does not add any additional information 
such as implemented patterns or relations between them. These additional 
information should be added by instances of \inlinecode{IDiagramUpdater} interface, 
whose method \inlinecode{UpdateDiagram} is always invoked when a 
new assembly is added to the diagram. Most of the classes that implement 
the \inlinecode{IDiagramUpdater} interface are also diagram visitors and 
the implementation of the \inlinecode{UpdateDiagram} method is just 
call to the diagram's \inlinecode{Visit} method supplying itself as 
an argument. These "diagram updaters" implement discovery of relations and 
implemented design patterns.

\subparagraph*{}
All the objects are, as in the case of Pattern Enforcer, composed together 
using the Managed Extensibility Framework (MEF).



%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
%-------------------------------------------------------------------------------------------------
\section{Related Work}

\subparagraph*{}
According to \cite{bruhlmann2010enriching} published in the year 2010 only 
a few approaches to reverse engineering that use additional information provided 
by developers exist. We are not aware of any reverse engineering tool that 
explicitly supports design patterns and use additional information provided 
by human beings. Tools that support UML standard might be, however, extended with 
stereotypes that could express implemented design patterns.

\subparagraph*{}
To provide more views on the same system each of them with different 
level of abstraction is the main idea behind Model Driven Development (MDA). 
In contrast to Architecture Explorer, MDA does not only address design patterns 
but also platform independence, transformation from higher abstract models to 
more specific models or source code, and other issues. MDA is a standard 
maintained by Object Management Group and this standard has to be implemented 
by concrete tools.

\paragraph*{Pattern recognition tools.}
\subparagraph*{}
A tool presented in \cite{majtas2011patterns} provides design patterns 
instances recognition based on static and dynamic analysis. 
It might be interesting in the context of 
Patterns4Net, because it one of the few design patterns tools that 
targets the .NET platform. Authors also process the intermediate language, 
but they use standard .NET reflection.

\subparagraph*{}
The idea that information about implemented design patterns might help 
to provide several views on the same system but with different level of 
abstraction is also discussed in \cite{ArcelliFontana2011marple}. 
The authors propose an Eclipse plug-in called MARPLE 
(Metrics and Architecture Reconstruction Plug-in for Eclipse), 
which could automatically recognize design patterns in Java code and then 
display special diagrams. The authors of MARPLE also plan to 
take advantage of Graphviz -- a graph vizualization tool.

\paragraph*{UML reverse engineering.}
\subparagraph*{}
The software called UMLGraph (\cite{umlgraph:Online}) provides automated drawing of UML 
diagrams extracted from java source code. It uses Graphviz for vizualization and 
call graph analysis for discovery of relationships in similar way we do 
in Architecture Explorer. UMLGraph uses Graphviz directly to generate SVG 
images. On contrary, in Architecture Explorer we process the output of Graphviz 
and convert it to WPF controls in order to provide interactivity in the user 
interface.








